home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE4 / ZAP / !Zap / Modules / !ZapJRF / !Help next >
Text File  |  2002-05-08  |  7KB  |  170 lines
  1.                                 ZapJRF
  2.                                 ======
  3.  
  4. Introduction
  5. ------------
  6. This module began life as 'ZapDecimal' because of a minor bug in version 1.20
  7. of Zap. The bug was fixed in 1.30, but the name sort of stuck. However, any
  8. copies of that module should be deleted and this version used instead.
  9.  
  10. In this module are a few useful commands:
  11.    JRF_IF          Conditional execution based on the text at the cursor
  12.    RUNSCRIPT       Execute a 'script' file
  13.    JRF_MENUFORMODE
  14.  
  15. Note that ZapJRF is no longer being maintained. The remaining functionality
  16. will be moved into other extensions.
  17.  
  18. JRF_IF
  19. ------
  20. Syntax:  JRF_IF <break><compare><break><then clause>
  21.     or:  JRF_IF <break><compare><break><break><else clause>
  22.     or:  JRF_IF <break><compare><break><then clause><break><else clause>
  23. Purpose: Conditional execution based on the text at the cursor
  24. Description:
  25.   Whilst working in the HTML modes I found it useful to be able to do things
  26.   depending on what was already at the cursor. JRF_IF allows you to check the
  27.   text at the cursor and execute one of two different sets of instructions
  28.   depending on whether the text and your string are the same.
  29.   Comparison is case insensitive and control characters can be checked by
  30.   using |<character> in the same way as the *Echo command.
  31.   A large stack is installed when you execute this command because depths
  32.   of around 6 JRF_IF's mean that there is no longer any stack space to run
  33.   commands.
  34.   Remember that such a depth results in 64 consecutive " symbols appearing
  35.   consecutively. Whilst this is allowable, and I have safely executed
  36.   commands with over 1024 consecutive "'s in them, this is NOT recommended.
  37.   Special checks are present in this code to extend the stack as at this level
  38.   of complexity the standard stack is not large enough.
  39.   If you wish to write such complex commands, do it as an extension module,
  40.   or use RUNSCRIPT.
  41.  
  42.  
  43. RUNSCRIPT
  44. ---------
  45. Syntax:  RUNSCRIPT "<filename>"
  46. Purpose: Execute a 'script' file (or from memory)
  47. Description:
  48.   This is arguably the most powerful Zap command I've written. At least I
  49.   argue it. The file (or memory) you specify will be read in, a line at a
  50.   time, and each command executed. There are also special functions available
  51.   in script files :
  52.     #IfText "<text>"
  53.       Like JRF_IF, this will perform a comparisson on the text at the cursor
  54.       and, if they are the same, execute the next block of code. In addition
  55.       to the escaped characters in JRF_IF, you can also use |" to escape a "
  56.       symbol.
  57.     #IfMode <mode>[{,<mode>}]
  58.       Like MJE_IFMODE, this will perform a check on the current mode before
  59.       executing the next block of code.
  60.     #IfModeN <mode name>[{,<mode>}]
  61.       This is identical to #IfMode, except that it requires mode names.
  62.     #Else
  63.       Inverts the execution state (if we are executing this block).
  64.     #EndIf
  65.       Ends the current If statement.
  66.     |<anything>
  67.       Is ignored.
  68.     #Stop
  69.       Stops execution at the current point (obeying 'if's)
  70.     #ScriptEnd
  71.       Marks the end of a script (only really useful in JRF_SCRIPTADDR where
  72.       it MUST be used).
  73.  
  74.   If statements can be nested up to 256 levels - this is still poorly managed
  75.   but should be adequate for most uses. Lines in scripts MUST NOT exceed 255
  76.   characters currently.
  77.  
  78.  
  79. Scripting directive additions
  80. -----------------------------
  81. You can write modules which provide their own scripting directives to
  82. supplement the built in ones. To do this you should recognise the following
  83. service calls :
  84.  
  85. Service_ZapJRFScripts &90480 (not officially allocated and picked at random)
  86.   => r0 = reason
  87.           (0 = starting, 1 = dying)
  88.      r1 = &90480
  89.   
  90.   This service is issued as ZapJRF starts and shuts down. You should call
  91.   ZapJRF_RegisterScriptDirectives or ZapJRF_DeRegisterScriptDirectives 
  92.   respectively.
  93.   You should not claim this service. 
  94.   
  95. ZapJRF_RegisterScriptDirectives
  96.   => r0-> table of directives, of the form :
  97.           <zero-terminated capitalised string>
  98.           <offset>
  99.           repeated, and terminated with a null string (ie 0 byte)
  100.      r1-> base of offsets (ie, where the offsets are from)
  101.      r2 = private word
  102.   
  103.   You should call this to register your script directives table. This should
  104.   be done on initialisation and when receiving Service_ZapJRFScripts with
  105.   reason = 0.
  106.  
  107. ZapJRF_DeRegisterScriptDirectives
  108.   => r0-> table of directives, of the form :
  109.           <zero-terminated capitalised string>
  110.           <offset to routine>
  111.           repeated, and terminated with a null string (ie 0 byte)
  112.      r1-> base of offsets (ie, where the offsets are from)
  113.      r2 = private word
  114.   
  115.   You should call this to deregister your script directives table. This
  116.   should be done on finalisation and when receiving Service_ZapJRFScripts
  117.   with reason = 1. The registers passed should all be the same as when
  118.   originally passed.
  119.  
  120. Routines will be called with the following parameters :
  121.   => r0-> first valid character (if any)
  122.      r2 = character we stopped on (32 for params, 0 if none)
  123.      r3 = private word
  124.      r4-> 'if structure'
  125.      r5 = 'if structure' offset (depth)
  126.      r6-> start of line buffer (add 256 for a temporary buffer)
  127.      r7 reserved for future update
  128.      r8-> window block (as for Zap)
  129.      r9-> file block (as for Zap)
  130.      r10-> cursor block (as for Zap)
  131.      r11 = 1 if command should be done ('if' state)
  132.      r12-> zap workspace
  133.      r13-> full descending stack (of unspecified length)
  134.      r14-> return address
  135.  
  136.   <= r7,r12 preserved
  137.      r8,r9,r10 preserved or updated
  138.      r5 preserved or incremented/decremented by 1
  139.      r11 preserved, or toggled for 'if's, or set to 2 to stop
  140.      r0-r4,r6 corrupt
  141.      Do NOT restore flags on return
  142.  
  143.   You will be able to call any Zap routine with the standard FNcall()
  144.   code. Try not to write code which dies :-)
  145.  
  146.  
  147. History (Note, Justin: You must assemble this with BasicVExt installed)
  148. -------
  149. Version 1.24 : 28 Feb 2000
  150.                Most commands have now been moved into other extensions.
  151. Version 1.20 : 07 May 1997
  152.                Bug in JRF_SCRIPTADDR fixed (ValidateAddress).
  153. Version 1.19 : 03 Apr 1997
  154.                Multiple script directive tables now supported.
  155. Version 1.18 : 02 Apr 1997
  156.                Renamed JRF_INSERTFILE to INSERTFILE and JRF_DOFILE to
  157.                RUNSCRIPT. JRF_SCRIPTADDR written.
  158.                Scripts should now use | as comments. #ScriptEnd and #Stop
  159.                added.
  160. Version 1.17 : 19 Mar 1997
  161.                Scripting added using JRF_DOFILE.
  162. Version 1.15 : 12 Mar 1997
  163.                Insertion of lumps of text with JRF_INSERTFILE implemented
  164.                JRF_UPDATEWINDOW killed - use TMT_UPDATEWINDOW in preference.
  165.                (As of 23 May 1997, use UPDATEWINDOW in preference)
  166. Version 1.13 : 05 Dec 1996
  167.                Renamed to ZapJRF and other changes.
  168. Older versions : Sometime long ago
  169.                  Who cares what happened to them... they're dead and buried.
  170.